home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac 1993 September / September 93.iso / Archives / Applications / Graphics / Fractals / Mandelzot 3.0.7 / ECI.h next >
Encoding:
C/C++ Source or Header  |  1990-10-17  |  14.4 KB  |  407 lines  |  [TEXT/KAHL]
  1. /*
  2.         Data definitions for the MandelZot external function
  3.         interface.
  4. */
  5.  
  6. #include <MacTypes.h>
  7.  
  8. #define ECIVERSION 0x0100        /* version 1.0 per Apple's numbering style */
  9.  
  10. typedef union Arg                        /* Argument variants */
  11.     {
  12.         void                 *p;                        /* generic pointer */
  13.         Handle                h;                        /* generic handle */
  14.         char                    c;                        /* single character */
  15.         char                    bool;                    /* one-byte boolean */
  16.         short int            si;                        /* 16-bit integer */
  17.         long int            li;                        /* 32-bit integer */
  18.         long int            flags;                /* 32 one-bit flags */
  19.         float                    f;                        /* SANE/IEEE single-precision floating */
  20.         short double  d;                        /* SANE/IEEE double-precision floating */
  21.         double                e;                        /* SANE *or* IEEE extended-precision */
  22.         Rect                    r;                        /* QuickDraw rectangle */
  23.         char                    filler[12];
  24.     } Arg;
  25.  
  26. typedef struct ECD                    /* External Code descriptor */
  27.     {
  28.         Handle                private;            /* handle to module-specific private data, if any */
  29.         int                        resFileRefNum;/* refNum of resource file, if open... or 0 */
  30.         long int            opaque[];            /* remainder of structure is opaque to the ECM */
  31.     } ECD, **ECDHandle;
  32.  
  33. typedef struct ECP                    /* External Code parameter structure */
  34.     {
  35.         long int            functionCode;    /* function code being requested */
  36.         Arg                        arg[16];            /* up to 16 arguments per call */
  37.     } ECP, **ECPHandle;
  38.  
  39. typedef struct ECO                    /* External Code overhead structure */
  40.     {
  41.         ECDHandle            ECD;                    /* handle to code descriptor structure */
  42.         Handle                viewHandle;        /* opaque handle to view structure */
  43.         Handle                private;            /* handle to view-specific private data, if any */
  44.         long int            (*util)();        /* pointer to MandelZot "pascal" utility callback */
  45.     } ECO, **ECOHandle;
  46.  
  47. /*
  48.         Data bits describing ECM's requirements
  49. */
  50.  
  51. #define NeedFPU                        0x80000000
  52. #define NeedIEEEformat        0x40000000
  53. #define NeedResources            0x20000000
  54. #define NeedLockSelf            0x10000000
  55. #define NeedLockAll                0x08000000
  56. #define NeedConfigure            0x04000000
  57.  
  58. /*
  59.         Data bits describing ECM's capabilities
  60. */
  61.  
  62. #define DoMarianiSilver        0x80000000
  63. #define DoDistEstimator        0x40000000
  64. #define DoJulias                    0x20000000
  65. #define DoByPoint                    0x10000000
  66. #define DoByBatch                    0x08000000
  67. #define DoBroadband                0x04000000
  68.  
  69. /*
  70.         Data bits describing symmetry
  71. */
  72.  
  73. #define SymmetryHoriz            0x0001
  74. #define SymmetryVert            0x0002
  75. #define SymmetryOrigin        0x0004
  76.  
  77. /*
  78.         Data bits describing math modes supported/used
  79. */
  80.  
  81. #define Math16bit                    0x0001
  82. #define Math32bit                    0x0002
  83. #define MathSANE                    0x0004
  84. #define Math881                        0x0008
  85.  
  86. /*
  87.         Values returned from the CalcTimeSlice call
  88. */
  89.  
  90. #define SliceSuspend            -1
  91. #define SliceOK                        0
  92. #define SliceIdle                    1
  93. #define SliceDone                    2
  94.  
  95. /*
  96.         File and resource types etc.
  97. */
  98.  
  99. #define CustomFileType        'CUST'
  100. #define CustomResType            'CUST'
  101. #define CustomResID                0
  102. #define CustomResRange        1024
  103. #define CustomResRangeEnd    2047
  104.  
  105. /*
  106.         Values and masks for dwell counts.
  107.         
  108.         Dwell values are stored in 16-bit integers.  The rightmost 15 bits
  109.         are the dwell value (in the range 0 through 32765), or "in the M-set"
  110.         (32766) or "unknown at this time" (32767).  The leftmost bit is a flag
  111.         used to indicate that the value in the rightmost 15 bits is approximate
  112.         or inexact, and should be recalculated;  this bit is set when a window is
  113.         resized upwards, or the calculation parameters are changed.
  114.         
  115. */
  116.  
  117. #define MaxLegalDwell    32765
  118. #define InTheSet            32766
  119. #define Unknown                32767
  120. #define RecalcBit            0x8000
  121. #define DwellMask            0x7FFF
  122.  
  123. /*
  124.         Function codes passed in to ECM from the program
  125. */
  126.  
  127. enum ECFunction
  128.     {
  129.         GetGeneralInfo                = 0,
  130.         InitECM                                = 1,
  131.         GetDefaults                        = 2,
  132.         SetupView                            = 3,
  133.         ConfigureView                    = 4,
  134.         SetupCalcs                        = 5,
  135.         CalcsGo                                = 6,
  136.         CalcsStop                            = 7,
  137.         CalcOne                                = 8,
  138.         CalcTimeSlice                    = 9,
  139.         KillView                            = 10,
  140.         KillECM                                = 11,
  141.         GetViewInfo                        = 12,
  142.         InvalInternals                = 13,
  143.         GetViewString                    = 14
  144.     };
  145.  
  146. /*
  147.         Parameter definitions for the various callins
  148.         
  149.         "->" represents a value passed into the ECM
  150.         "<-" represents a value filled in by the ECM prior to returning.
  151.  
  152. ---
  153.  
  154.         GetGeneralInfo.  Called during program initialization.  ECM should fill in
  155.         specified values and return, taking no other actions.  [N.B.  This is the
  156.         only callin which can occur before the first InitECM.]
  157.  
  158.         [0].si            ->        Interface version against which program was compiled.
  159.         [0].si            <-        Interface version number against which the ECM was
  160.                                             compiled.  If too old, ECM will not be usable.
  161.         [1].flags        <-        "Needs" flags, or'ed together
  162.         [2].flags        <-        "Does" flags, or'ed together.
  163.         [3].flags        <-        "Math" flags, or'ed together
  164.  
  165. ---        
  166.         
  167.         InitECM.  Called when ECM's code resource is first read in.  ECM should set
  168.         up any desired global-state code, storing handle into the ECD structure.
  169.         
  170.         No data is passed in or out.
  171.  
  172. ---
  173.  
  174.         GetDefaults.  Called during the "New view" dialog, when an ECM is selected from
  175.         the popup menu, or when the julia-set status box changes.
  176.         
  177.         [0].bool        ->        if true, the ECM should return the appropriate default
  178.                                             values for a Julia-set image.  If false, the ECM should
  179.                                             return the appropriate defaults for an M-like image.
  180.         
  181.         [0].d                <-        Minimum real value displayed in window
  182.         [1].d                <-        Maximum real value displayed in window
  183.         [2].d                <-        Minimum imaginary value displayed in window
  184.         [3].d                <-        Maximum imaginary value displayed in window
  185.         [4].si            <-        Dwell limit [0..32765]
  186.         [5].d                <-        Escape radius
  187.         [6].d                <-        Julia control point, real (iff julia image requested)
  188.         [7].d                <-        Julia control point, imaginary (iff julia image requested)
  189.  
  190. ---
  191.  
  192.     ConfigureView.  Called when the user presses the "Setup" botton in the
  193.     New View dialog box (and also when the ECM is initially selected from
  194.     the popup menu).  The ECM may pop up a dialog box to allow
  195.     the user to enter configuration information (e.g. equation coefficients,
  196.     network-server name/ID, etc.).  All such data should be stored in a relocatable
  197.     block allocated by the ECM, whose handle is stored in the ECO structure.
  198.     This routine may be called multiple times, to update the configuration.
  199.     
  200.         [0].bool        ->        nonzero if Julia calculation, zero if M calculation
  201.  
  202. ---
  203.  
  204.     GetViewInfo.  Called after the view data structure has been initialized, and
  205.     before calculation begins.  ECM must return information about the characteristics
  206.     of the view:  whether the distance-estimator feature is available, whether the
  207.     Mariani-Silver algorithm should be enabled, information concerning the symmetry
  208.     of the resulting image, etc.
  209.  
  210.         [0].e                ->        Minimum real value displayed in window
  211.         [1].e                ->        Maximum real value displayed in window
  212.         [2].e                ->        Minimum imaginary value displayed in window
  213.         [3].e                ->        Maximum imaginary value displayed in window
  214.         [4].si            ->        Dwell limit [0..32765]
  215.         [5].d                ->        Escape radius
  216.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  217.         [7].e                ->        Julia control point, real (iff julia image requested)
  218.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  219.         
  220.         [0].bool         <-        nonzero if distance-estimator capability is available
  221.         [1].bool        <-        nonzero if Mariani/Silver algorithm is suitable
  222.         [2].flags        <-        symmetry characteristics: horizontal, vertical, across-origin,
  223.                                             or an or'ed combination thereof.
  224.         [3].e                <-        real axis of symmetry, if any symmetry is specified
  225.         [4].e                <-        imaginary axis of symmetry, if any symmetry is specified
  226.  
  227. ---
  228.  
  229.     SetupCalcs.  Called when the view data structure has been initialized, and
  230.     calculation is about to begin.  ECM should set up any data it needs to perform
  231.     the calculation, based on the current calculation parameters.  May be called
  232.     more than once, if the user changes the calculation parameters.
  233.     
  234.         [0].e                ->        Minimum real value displayed in window
  235.         [1].e                ->        Maximum real value displayed in window
  236.         [2].e                ->        Minimum imaginary value displayed in window
  237.         [3].e                ->        Maximum imaginary value displayed in window
  238.         [4].si            ->        Dwell limit [0..32765]
  239.         [5].d                ->        Escape radius
  240.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  241.         [7].e                ->        Julia control point, real (iff julia image requested)
  242.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  243.         [9].bool        ->        nonzero if distance-estimator, zero if point-by-point
  244.         [10].r            ->        Rectangle framing the window
  245.  
  246. ---
  247.  
  248.     CalcsGo.  Called when the program has decided to start calling CalcTimeSlicd.
  249.     ECM should grab any resources needed to do calculation (external hardware,
  250.     network calculation server, etc.).
  251.  
  252.     No parameters at this time;  success is assumed.
  253.  
  254. ---
  255.  
  256.     CalcsStop.  Called when the program has decided to stop calling CalcTimeSlice.
  257.     ECM should release any resources it grabbed at CalcsGo time.
  258.  
  259.     No parameters at this time;  success is assumed.
  260.  
  261. ---
  262.  
  263.     CalcOne.  Called to request calculation of the dwell (and, optionally,
  264.     distance-to-nearest-interior-point) of a single point.
  265.     
  266.         [0].e                ->         Real coordinate of point
  267.         [1].e                ->        Imaginary coordinate of point
  268.         [2].si            ->        Dwell limit
  269.         [3].d                ->        Escape radius
  270.         [4].bool        ->        nonzero if Julia calculation, zero if M calculation
  271.         [5].bool        ->        nonzero if distance-estimator, zero if point-by-point
  272.         [6].e                ->        Julia control point, real (iff julia image requested)
  273.         [7].e                ->        Julia control point, imaginary (iff julia image requested)
  274.         [8].flags        ->        Flag indicating math mode in use
  275.  
  276.         [0].si            <-        Dwell of point [0..limit), or
  277.                                             "on border" == limit, or
  278.                                             "in M"            == 32766 (InTheSet).
  279.         [1].e                <-        Estimated distance to nearest interior point (iff
  280.                                             distance-estimator mode), or -1 == "beats me!"
  281.  
  282. ---
  283.  
  284.     CalcTimeSlice.  Called to give a bulk-calculation-mode ECM an opportunity to
  285.     calculate something.  CalcTimeSlice calls will occur in the middle of a
  286.     CalcGo/CalcStop pair.  ECM should do some calculating, if possible;  stuff
  287.     dwell values into the array;  and use callbacks to instruct the program to
  288.     display points/lines/rectangles of data values on the screen.  ECM can draw to
  289.     the window if desired (it's the current GrafPort).
  290.     
  291.         [0].e                ->        Minimum real value displayed in window
  292.         [1].e                ->        Maximum real value displayed in window
  293.         [2].e                ->        Minimum imaginary value displayed in window
  294.         [3].e                ->        Maximum imaginary value displayed in window
  295.         [4].si            ->        Dwell limit [0..32765]
  296.         [5].d                ->        Escape radius
  297.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  298.         [7].e                ->        Julia control point, real (iff julia image requested)
  299.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  300.         [9].bool        ->        nonzero if distance-estimator, zero if point-by-point
  301.         [10].r            ->        Rectangle framing the window
  302.         [11].r            ->        Rect which frames entire array (if calculation is not currently
  303.                                             constrained) or frames constrained area.  ECM should limit its
  304.                                             calculations and drawing to points within this rectangle.
  305.         [12].h            ->        Handle to array of dwell values, stored in row-major order
  306.         [13].flags    ->        Flag indicating math mode in use
  307.         
  308.         [0].si            <-        SliceOK if all is well and useful work was done;
  309.                                             SliceIdle if all is well but nothing much happened (little time used);
  310.                                             SliceDone if all is well and calculations for the area framed by
  311.                                             the [11].r parameter have been completed;
  312.                                             SliceSuspend if something has gone awry and calculations should
  313.                                             be suspended until the user hits command-G again.
  314.  
  315. ---
  316.  
  317.     InvalInternals.  Called when MandelZot loads a view's private data from a save-
  318.     file, or after an "Extract selection" command.  Call informs ECM that any pointers
  319.     or handles stashed in the view's private data block are no longer valid... they may
  320.     point to the parent window's private data (after an "Extract selection) or to
  321.     memory locations from a former lifetime (after loading a save-file).  ECM should zap
  322.     any pointers or handles (reset them to NULL, or allocate new blocks of the necessary
  323.     sizes and replace the old handles).  ECM should _not_ attempt to access, or dispose of
  324.     blocks referenced by the invalidated handles or pointers... they're off limits!!
  325.         
  326. ---
  327.  
  328.     GetViewString.  Called when the program wants a human-readable interpretation
  329.     of the view's private data.  ECM should convert relevant portions of the
  330.     private data (e.g. polynomial coefficients, exit conditions, etc.) to printable
  331.     form, and return them in the form of a PASCAL string of up to 255 characters.
  332.     
  333.         [0].p                ->        Pointer to an Str255 (PASCAL string) of indeterminate
  334.                                             contents;  program should stuff string into this structure.
  335.  
  336. */
  337.  
  338. /*
  339.         Function codes which the ECM can use when calling back to the main program
  340. */
  341.  
  342. enum CallbackFunction
  343.     {
  344.         DisplayPoint                    = 100,
  345.         DisplayRowSeg                    = 101,
  346.         DisplayRect                        = 102,
  347.         SetPenColor                        = 103,
  348.         SetStatusString                = 104
  349.     };
  350.  
  351. /*
  352.         Parameter definitions for the various callbacks
  353.         
  354.         "->" represents a value passed by the ECM to the program's callback routine
  355.         "<-" represents a value filled in by the callback prior to returning.
  356.         
  357.         DisplayPoint.  Used to ask the program to display a specified dwell-point in the
  358.         window.  ECM must stuff the dwell value into the dwell array before making this
  359.         call.
  360.         
  361.         [0].si            ->        X coordinate of point to be displayed
  362.         [1].si            ->        Y coordinate of point to be displayed
  363.  
  364. ---
  365.  
  366.         DisplayRowSeg.  Used to ask the program to display one or more dwell
  367.         points in a specified row.  ECM must stuff the values into the dwell array before
  368.         making this call.
  369.         
  370.         [0].si            ->        X coordinate at left end of row segment.
  371.         [1].si            ->        X coordinate at right end of row segment.
  372.         [2].si            ->        Y coordinate of row.
  373.  
  374. ---
  375.  
  376.         DisplayRect.  Used to ask the program to display a rectangular portion of the
  377.         view window, using the current dwell values for those points.
  378.         
  379.         [0].r                ->        Rect specifying the area to be displayed.
  380.         
  381.         n.b. the display occurs when the call is made.  Another way to do this is to
  382.         simply InvalRect(&rect);  the program will erase and redraw the specified
  383.         rectangle the next time around the event loop.
  384.  
  385. ---
  386.  
  387.         SetPenColor.  Used to ask the program to set the port's pen to the proper
  388.         color for drawing points of a specific dwell.
  389.         
  390.         [0].r                ->        Dwell value for which pen color should be set.
  391.         
  392.         n.b. ECM should reset the pen to black before returning.
  393.  
  394. ---
  395.  
  396.         SetStatusString.  Used to ask the program to update the status advisory
  397.         displayed (sometimes) in the horizontal scroll bar area.
  398.         
  399.         [0].p                ->        Pointer to Pascal Str255 string to be displayed.
  400.         
  401.         n.b. the specified string may or may not actually be displayed, at this
  402.         time or later.  This feature should be used for "FYI" information only;
  403.         it's not suitable for use in developing any sort of real user interface.
  404.  
  405. */
  406.  
  407.